\section{Spring RTS}

Spring provides an infrastructure to easily connect new AI modules through any
of its wrapper interfaces. Those wrappers encapsulate the SpringRTS interface in
the chosen programming language. One of those wrappers is the Java wrapper that
we will use when developing our own system.

Except for {\it Getting Started}
manuals\footnote{\url{http://springrts.com/wiki/AI:Development:Lang:Java}},
useful at first steps of project creation, we did not find documentation about
internal running of the wrappers. Therefore, we had to learn about the platform
in an inductive way. This was done implementing a GUI to command our Spring
Agent, described in \autoref{app:GUIboss}.

\subsection{World interaction}

Agents can interact with the environment in only two ways, observing the world
and acting on him.  In the real world, perception is done using sensors and
actions are made using actuators.  But in SpringRTS, the actuators are named
commands and the the closest thing to sensors are events and callbacks.

Everything remarkable in SpringRTS is an {\bf event}. Whenever an enemy unit is
spotted, a new unit is created or a building finished, for example, SpringRTS
notifies the AI with a new event. Those events are sent through a Java interface
and should be captured by our AI module.

{\bf Callbacks} are the channel through which our module communicates with the
SpringRTS Platform when requesting actions. There is a callback object that
holds the reference for this communicating channel. Here we can distinguish
between two types of communication, whenever we need information about the
environment (read-only) and when we want to perform actions that change the
world. For the former, especial functions are provided to ask the platform. For
the latter, all the changing world actions must be packed in a special structure
called {\bf Command} that is sent to the platform.

\subsubsection{Events}

This section outlines the different SpringRTS events and what should happen for
they to be sent (shown in \autoref{tab:SpringRTSevents}).  Moreover, there are a
brief explanation about confusing terms and peculiarities discovered during the
implementation.

\begin{table}[htp]
	\centering
		\begin{tabular}{| l | p{11cm} |}
		\hline
		\rowcolor[rgb]{0.8,0.8,0.8} AI event & Description\\
		\hline
		commandFinished & This AI event is sent when a unit finished processing
		a command\\
		\hline
		enemyDamaged & This AI event is sent when an enemy unit was damaged\\
		\hline
		enemyDestroyed & This AI event is sent when an enemy unit was
		destroyed\\
		\hline
		enemyEnterLOS & This AI event is sent when an enemy unit entered the
		Line Of Sight covered area of this team \\
		\hline
		enemyEnterRadar & This AI event is sent when an enemy unit entered the
		radar covered area of this team \\
		\hline
		enemyLeaveLOS & This AI event is sent when an enemy unit left the Line
		Of Sight covered area of this team \\
		\hline
		enemyLeaveRadar & This AI event is sent when an enemy unit left the
		radar covered area of this team \\
		\hline
		message & This AI event is a notification about a chat message sent by
		one of the participants of this game, which may be a player or an AI,
		including this AI \\
		\hline
		seismicPing & This AI event is sent when a unit movement is detected by
		means of a seismic event \\
		\hline
		unitCaptured & This AI event is sent when a unit changed from one team
		to an other through capturing \\
		\hline
		unitCreated & This AI event is sent whenever a unit of this team is
		created, and contains the created unit \\
		\hline
		unitDamaged & This AI event is sent when a unit was damaged \\
		\hline
		unitDestroyed & This AI event is sent when a unit was destroyed \\
		\hline
		unitFinished & This AI event is sent whenever a unit is fully built, and
		contains the finnished unit \\
		\hline
		unitGiven & This AI event is sent when a unit changed from one team to
		an other either because the old owner gave it to the new one, or because
		the new one took it from the old one \\
		\hline
		unitIdle & This AI event is sent when a unit finnished processing a
		command or just finished building, and it has currently no commands in
		it's queue \\
		\hline
		unitMoveFailed & This AI event is sent when a unit received a move
		command and is not able to fullfill it\\
		\hline
		weaponFired & This AI event is sent when a weapon is fired \\
		\hline
	\end{tabular}
	\caption{SpringRTS AI events}
	\label{tab:SpringRTSevents}
\end{table}

It is important to take into account that radar and line of sight (LOS) events are
referred to the total area covered by the team. Therefore, if one single unit
knows the position of an enemy unit, all the team has this knowledge.

Still on the subject of visibility, it is important to say that radar covers a
larger extension than LOS and it allows us to know some unit issues like
position, team or ID. But we can only know the unit type and complete definition
of the enemy units if they are in LOS of our team.

Moreover, is important to not misunderstand between the events {\it unitCreated}
and {\it unitFinished}.  Reading these names seems that may represent the same
situation, but it is not true. These events are different and easily
understandable: {\it unitCreated} event is sent each time starts a unit
construction, and {\it unitFinished} event is sent when the construction is
finished.

\subsubsection{Callbacks}

As mentioned in previous sections, {\it callbacks} are the channel through which
our module communicates with the SpringRTS Platform when requesting actions.
There is a callback object that holds the reference for this communicating
channel. Specifically, this is an {\it OOAICallback} object and provides several
methods that allows the agent to call the platform for specific information. The
methods used in this work and other useful methods are explained in
\autoref{tab:CallbackMethods}.

\begin{table}[htp]
	\centering
		\begin{tabular}{| l | p{9cm} |}
		\hline
		\rowcolor[rgb]{0.8,0.8,0.8} Callback method & Description\\
		\hline
		getEconomy() & Returns an {\it Economy} object, which give us
		information about storage, income or current state of each resource
		available in the map. \\
		\hline
		getEnemyUnits() & Returns all units that are not in this teams ally-team
		nor neutral and are in LOS. \\
		\hline
		getEnemyUnitsInRadarAndLos() & Returns all units that are not in this
		teams ally-team nor neutral and are in some way visible (sight or
		radar). \\
		\hline
		getEngine() & Returns a {\it Engine} object, which allow to ask several
		information about the Spring Engine and handle commands:
		{\it getEngine().handleCommand} \\
		\hline
		getFeatures() & Returns all features on the map. \\
		\hline
		getFeatureDefs() & Returns the definitions of all features on the map. \\
		\hline
		getFriendlyUnits() & Returns all units that are in agent team or
		ally-teams. \\
		\hline
		getMap() & Returns a {\it Map} object, which give us all information
		about the current map: the complete topography, where are the best
		positions to place metal extractors, etc. \\
		\hline
		getMod() & Returns a {\it Mod} object, which allow us to ask the
		complete information about the current mod. \\
		\hline
		getNeutralUnits() & Returns all units that are neutral and are in LOS. \\
		\hline
		getResources() & Returns all the resources available in the current
		map.\\
		\hline
		getTeamUnits() & Returns all units that are of the team controlled by
		this AI instance. \\
		\hline
		getUnitDefs() & Returns a list of all the available unit types in the
		game that is currently being played. \\
		\hline
	\end{tabular}
	\caption{OOAICallback methods}
	\label{tab:CallbackMethods}
\end{table}


\subsubsection{Commands}

As is said in previous sections, to change the world in SpringRTS we have to
send commands ({\it AOCommand} objects) to the platform through a {\it
OOAICallback} object. SpringRTS has a huge number of AICommands to achieve
diverse actions; from path setting commands or adding units to groups, until
draw figures in the screen. The commands used in this work are explained in
\autoref{tab:SpringAICommands}.

\begin{table}[htp]
	\centering
		\begin{tabular}{| l | p{10.5cm} |}
		\hline
		\rowcolor[rgb]{0.8,0.8,0.8} AICommand & Description\\
		\hline
		AttackUnitAICommand & This object packs the unit we want to give the
		order to attack and the target unit. \\
		\hline
		BuildUnitAICommand & This object packs the unit we want to give the
		order to build, the construction definition, the building point and the
		orientation. \\
		\hline
		MoveUnitAICommand & This object packs the unit we want to give the order
		to move and the destination point. \\
		\hline
	\end{tabular}
	\caption{Spring AI Commands}
	\label{tab:SpringAICommands}
\end{table}

Besides the descriptions of \autoref{tab:SpringAICommands}, all the commands
explained also pack the maximum time allowed to fulfil the action, a list of
configuration options and the group ID.  The last one, the group ID, is useful
if we want to give the same order to a group of units.

\subsection{From events and callbacks to percepts}

In this section we have to define to ways of generate percepts from SpringRTS to
Jason.  On one hand, each time a relevant event is sent by Spring Engine, it is
caught and treated to be useful for Jason (shown in
\autoref{tab:Events2Percepts}). On the other hand, when Jason needs some
information about the environment and makes the question in a callback form, the
answer must be converted, too, in a Jason percept as shows
\autoref{tab:Callbacks2Percepts}.

\begin{table}[htp]
	\centering
	\begin{tabular}{ c c c c c }
		{\bf SpringRTS event} &  & {\bf Java Module} &  & {\bf Jason percept}\\
		\hline
		UnitFinished & $\longrightarrow$ & gameStarted & $\longrightarrow$ &
		Game Starts \\
	
		enemyEnterLOS & $\longrightarrow$ & enemyCommanderEnterLOS &
		$\longrightarrow$ & Enemy Commander in Los \\
	
		UnitFinished & $\longrightarrow$ & orderUnitsConstructed &
		$\longrightarrow$ & Order of units Constructed \\

		UnitFinished & $\longrightarrow$ & buildingConstructed &
		$\longrightarrow$ & Building Constructed \\
	\end{tabular}
	\caption{Equivalences from SpringRTS events to Jason percepts}
	\label{tab:Events2Percepts}
\end{table}

Perhaps, it may be strange (in \autoref{tab:Events2Percepts}) that {\it Game
Starts} percept comes from {\it UnitFinished} event.  This is because we have
considered that game starts when Java module takes the control of Spring
commander, and this occurs when the {\it commander} unit of our team is created,
i.e. when is received the {\it UnitFinished} event with the reference to our
commander.

\begin{table}[htp]
	\centering
	\begin{tabular}{ c c c c c }
		{\bf Callback method} &  & {\bf Java Module} &  & {\bf Jason percept}\\
		\hline
		getMap() & $\longrightarrow$ & getMapMeasures & $\longrightarrow$ &
		Measures of Map \\
		
		commander.getPos() & $\longrightarrow$ & getCommanderPosition &
		$\longrightarrow$ & Commander Position \\
			
		getEconomy() & $\longrightarrow$ & getMetalAvailable & $\longrightarrow$
		& Metal Available \\

		getEconomy() & $\longrightarrow$ & getEnergyAvailable &
		$\longrightarrow$ & Energy Available \\
				
		getUnitDefs() & $\longrightarrow$ & getMetalCost & $\longrightarrow$ &
		Unit Metal Cost \\

		getUnitDefs() & $\longrightarrow$ & getEnergyCost & $\longrightarrow$ &
		Unit Energy Cost \\
		
		getUnitDefs() & $\longrightarrow$ & getDependence & $\longrightarrow$ &
		Unit Tech Dependence \\
		\end{tabular}
	\caption{Equivalences from callback methods to to Jason percepts}
	\label{tab:Callbacks2Percepts}
\end{table}

To complete this section, should be added that most of the callback methods
showed in \autoref{tab:Callbacks2Percepts} are {\it getEconomy} end {\it
getUnitsDef} because these are, respectively, the generic methods that return
information about all the parameters related with resources and units in the
game.

\subsection{Form actions to commands}

Unlike the allocations specified in the previous section, these equivalences are
almost straightforward and, as indicated by their names in
\autoref{tab:Actions2Commands}, easy to understand. There are only an ambiguous
point: The Jason actions {\it Create Building} and {\it Create Unit} become the
same {\it BuildUnitAICommand}. This happens because conceptually is different to
construct a building than a mobile unit construction, but for Spring Engine is
the same, all are units.

\begin{table}[htp]
	\centering
	\begin{tabular}{ c c c c c }
		{\bf Jason action} &  & {\bf Java Module} &  & {\bf Spring AI Command}\\
		\hline
		Attack Unit & $\longrightarrow$ & attack & $\longrightarrow$ &
		AttackUnitAICommand \\

		Create Building & $\longrightarrow$ & constructBuilding &
		$\longrightarrow$ & BuildUnitAICommand \\

		Create Unit & $\longrightarrow$ & constructUnit & $\longrightarrow$ &
		BuildUnitAICommand \\

		Move Unit & $\longrightarrow$ & move & $\longrightarrow$ &
		MoveUnitAICommand \\
	\end{tabular}
	\caption{Equivalences from actions to commands}
	\label{tab:Actions2Commands}
\end{table}

\subsection{Interaction with Jason}

The Spring module implemented in this work has three main classes:

\begin{itemize}
	\item \texttt{MySpringAgent}: The kernel of the module. The sensors and the
		actuators of our system.
	\item \texttt{MySpringFactory}: Used in Sprinng engine interaction.
	\item \texttt{SpringBoss}: Used in interaction with the ``brain'' of the
		system. This class has two subclasses, depending of the ``type of
		brain'':
		\begin{itemize}
			\item \texttt{GUIboss}: Graphical Interface that allows to a human to
				send the orders and recieve the perceptions.
			\item \texttt{JASONboss}: Class responsible to command the
				\texttt{MySpringAgent} if is a Jason agent ho is sending the
				orders and receiving the perceptions
		\end{itemize}
\end{itemize}

The problem is that Spring requires to put the Java module in an specific folder
with a special properties, acting as a library, and it had problems with Jason
acting as a library. Therefore, we decided to implement two independent
modules, fisically separated and communicated with some development platform for
distributed systems.

The Jason module should have two main classes:

\begin{itemize}
	\item \texttt{SpringEnvironment}: Implements the Jason \texttt{Environment}
		class and should be the bridge between Java and Jason reasoning.
	\item \texttt{World}: Allows the interaction with the ``real world''. This
		class has two subclasses, depending on the ``world'' where Jason agent
		lives.
		\begin{itemize}
			\item \texttt{SimulatedWorld}: Useful for testing
			\item \texttt{SpringWorld}: Class responsible to catch the
				perceptions sent by Spring module and command the actions
				generated by Jason reasoning.
		\end{itemize}
\end{itemize}

The platform chosen to join both modules would be
CORBA\footnote{\url{http://en.wikipedia.org/wiki/Common_Object_Request_Broker_Architecture}}
(Common Object Request Broker Architecture) because facilitates remote method
invocation under an object-oriented paradigm. This would allow us to forget the
communication, using the same Java objects in both modules.


